Quarto HTML themes

Bootstrap and Bootswatch

Quarto’s HTML output uses Bootstrap (5.3) classes, and their default styles can be modified using Bootswatch themes.

Bootstrap styles are written in Sass, and customizations are implemented via a custom.scss file. In the simplest case it has the structure:

«default variable overrides»
@import "../node_modules/bootstrap/scss/bootstrap";
«additional custom code»

Each Bootswatch theme is defined by two files, _variables.scss and _bootswatch.scss, which are used in such a custom.scss:

@import "_variables.scss";
@import "../node_modules/bootstrap/scss/bootstrap";
@import "_bootswatch.scss";

Quarto uses a format for themes which combines _variables.scss and _bootswatch.scss in a single file:

/*-- scss:defaults --*/
«contents of _variables.scss»
/*-- scss:rules --*/
«contents of _bootswatch.scss»

The themes bundled with Quarto are essentially such a combination of the Bootswatch theme files, though some edits seem to have been made.

Theme files are of significantly different complexity, the simplest being united.scss at 77 lines, cosmo.scss at 107 lines, and journal.scss at 108 lines, and the most complex materia.scss at 777 lines. The absolutely simplest option is of course to use the default Bootstrap styles.

According to the documentation, more than the two sections derived from the Bootswatch format are supported in a theme file: uses, functions, defaults, mixins, and rules. Comparison with the Bootstrap documentation on customization does not clarify the use of these additional sections.

Using themes

A bundled HTML theme is used by specifying its name under the theme key, e.g.

format:
  html:
    theme: united

which results in the combination of the Bootswatch-derived united.css with the Bootstrap default styles. The theme default has no corresponding theme file because there are no modifications to be applied.

A custom theme can be specified through a Sass file theme.scss as above. It can either apply modifications on top of a bundled theme

format:
  html:
    theme:
      - united
      - theme.scss

or relative to the Bootstrap default styles:

format:
  html:
    theme: theme.scss

Specifying a bundled theme is therefore equivalent to

format:
  html:
    theme: /quarto-installation/…/themes/united.scss